User data and images topic
Mark favorites, played state and ratings, build and fetch images, and store display preferences.
User data
User data is what the server keeps for each user and item: favorite,
played, play count, resume position and rating. Each call below returns
the new JellyfinUserData.
Favorites
await jellyfin.userData.markFavorite(itemId: track.id);
await jellyfin.userData.unmarkFavorite(itemId: track.id);
// For a toggle:
await jellyfin.userData.setFavorite(itemId: track.id, isFavorite: true);
User data belongs to an item id. An artist from artists is a Person
item, so its favourite is the person's, not the MusicArtist's. See the
Library topic.
Played state and ratings
await jellyfin.userData.markPlayed(itemId: track.id);
await jellyfin.userData.markUnplayed(itemId: track.id);
await jellyfin.userData.rate(itemId: track.id, likes: true);
await jellyfin.userData.clearRating(itemId: track.id);
Reading and writing the record
final data = await jellyfin.userData.get(itemId: track.id);
print('position=${data.playbackPositionTicks} count=${data.playCount}');
// Reset the resume position, keep the rest.
await jellyfin.userData.update(
itemId: track.id,
userData: JellyfinUserData(
playCount: data.playCount,
isFavorite: data.isFavorite,
played: data.played,
playbackPositionTicks: 0,
),
);
Every user data call acts for the session's user; pass userId to
act for another.
Images
Image URLs follow a pattern, /Items/{id}/Images/{type}, with a tag
from JellyfinItem.imageTags that changes when the image does. The
server resizes, so the client needs no scaling.
With tag as the only parameter, the server sends the stored file as it
is. Any processing parameter (sizing, quality, blur,
percentPlayed, unplayedCount, backgroundColor) makes it re-encode.
Without format, it then picks the output from the request's Accept
header: WebP when that lists image/webp, as browsers and most image
widgets do, JPEG otherwise.
Building an image URL
final url = jellyfin.images.url(
itemId: track.artworkItemId ?? track.id,
tag: track.artworkVersion,
maxWidth: 512,
maxHeight: 512,
format: JellyfinImagesApi.formatJpg,
quality: 85,
);
type defaults to JellyfinImagesApi.typePrimary. The sizing
parameters:
| Parameters | Effect |
|---|---|
maxWidth, maxHeight |
Fit inside the box, aspect kept: the pair for a cover cache |
fillWidth, fillHeight |
Cover the box, aspect kept |
width, height |
Exactly those dimensions, stretched |
format picks the encoding (formatJpg, formatPng, formatWebp,
formatGif, formatBmp, formatSvg) and quality (0 to 100) applies
to the lossy ones. percentPlayed and unplayedCount draw a progress
bar and a badge into the image, and blur takes a radius. A
percentPlayed that is not finite throws an ArgumentError.
backgroundColor fills transparency and must be a hex RGB, ARGB,
RRGGBB or AARRGGBB, with an optional #. Any other value throws an
ArgumentError, because the server would drop the sizing too and send
the full original.
Fetching bytes
final Uint8List? bytes = await jellyfin.images.fetch(
itemId: track.artworkItemId ?? track.id,
tag: track.artworkVersion,
maxWidth: 512,
maxHeight: 512,
format: JellyfinImagesApi.formatJpg,
cancelToken: token, // drop it when the cell scrolls away
);
pathUrl() builds the same image with its size, format and version in
the path. Pair the version with its own id: artworkVersion with
artworkItemId, since a track's version may be its album's.
fetch() takes the sizing and encoding parameters of url() and a
cancelToken. It returns null on a 404 and throws a
JellyfinException on a transient failure, so "no image" and "try again
later" stay apart.
Image types and other images
| Constant | Wire value | Holds |
|---|---|---|
typePrimary |
Primary |
Album cover, movie poster, track art |
typeArt |
Art |
Clear art |
typeBackdrop |
Backdrop |
Backdrop |
typeBanner |
Banner |
Wide banner |
typeLogo |
Logo |
Title logo |
typeThumb |
Thumb |
Wide thumbnail |
typeDisc |
Disc |
Disc art |
Artists, genres, music genres, studios and people have images by name:
final artistUrl = jellyfin.images.artistImageUrl(
artistName: 'Aphex Twin',
maxWidth: 300,
maxHeight: 300,
);
final images = await jellyfin.images.listItemImages(itemId: album.id);
genreImageUrl(), musicGenreImageUrl(), studioImageUrl() and
personImageUrl() work the same way. listItemImages() returns each
image of an item as JellyfinImageInfo (type, index, tag, size,
dimensions). setItemImage(), deleteItemImage() and
reorderItemImage() edit an item's images; userImageUrl(),
uploadUserImage() and deleteUserImage() the user's own picture; and
splashscreenUrl() the login screen's background.
Display preferences
Display preferences are UI state the server stores for each user and
client: view type, sort order, scroll direction, and a free customPrefs
map. They follow the user across devices.
displayPreferencesId names the document, such as usersettings or a
library's id; client keeps one app's documents apart from another's.
Reading and writing
final prefs = await jellyfin.displayPreferences.get(
displayPreferencesId: 'usersettings',
client: 'my_app',
);
print('${prefs.viewType} sorted by ${prefs.sortBy}');
await jellyfin.displayPreferences.update(
displayPreferencesId: 'usersettings',
client: 'my_app',
preferences: const JellyfinDisplayPreferences(
id: 'usersettings',
client: 'my_app',
viewType: 'Poster',
sortBy: 'SortName',
sortOrder: 'Ascending',
rememberSorting: true,
),
);
Custom preferences
customPrefs is a Map<String, String> for your app's own state; the
server stores it without reading it:
await jellyfin.displayPreferences.update(
displayPreferencesId: 'usersettings',
client: 'my_app',
preferences: const JellyfinDisplayPreferences(
client: 'my_app',
customPrefs: {
'home.layout': 'compact',
'home.rails': 'continueWatching,nextUp,recentlyAdded',
},
),
);
Classes
- JellyfinDisplayPreferencesApi User data and images
-
/DisplayPreferences/*— per-client UI state, stored on the server so layout choices follow the user across devices. - JellyfinImagesApi User data and images
- Image URL builders + bytes fetch.
- JellyfinUserDataApi User data and images
- Favourites and played flags, plus the unified user-data record.